home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / GetGC.3 < prev    next >
Text File  |  1994-09-20  |  4KB  |  133 lines
  1.  
  2.  
  3.  
  4. Tk_GetGC(3)           Tk Library Procedures
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tk_GetGC, Tk_FreeGC - maintain database of read-only  graph-
  12.      ics contexts
  13.  
  14. SYNOPSIS
  15.      #include <tk.h>
  16.  
  17.      GC
  18.      Tk_GetGC(_t_k_w_i_n, _v_a_l_u_e_M_a_s_k, _v_a_l_u_e_P_t_r)
  19.  
  20.      Tk_FreeGC(_d_i_s_p_l_a_y, _g_c)                                        |
  21.  
  22. ARGUMENTS
  23.      Tk_Window       _t_k_w_i_n       (in)      Token  for  window  in
  24.                                            which   the   graphics
  25.                                            context will be used.
  26.  
  27.      unsigned long   _v_a_l_u_e_M_a_s_k   (in)      Mask of bits (such  as
  28.                                            GCForeground        or
  29.                                            GCStipple)  indicating
  30.                                            which     fields    of
  31.                                            *_v_a_l_u_e_P_t_r are valid.
  32.  
  33.      XGCValues       *_v_a_l_u_e_P_t_r   (in)      Pointer  to  structure
  34.                                            describing the desired
  35.                                            values for the  graph-
  36.                                            ics context.
  37.  
  38.      Display         *_d_i_s_p_l_a_y    (in)      Display for  which  _g_c
  39.                                            was allocated.          |
  40.  
  41.      GC              _g_c          (in)      X    identifier    for
  42.                                            graphics  context that
  43.                                            is no  longer  needed.
  44.                                            Must  have  been allo-
  45.                                            cated by Tk_GetGC.
  46. _________________________________________________________________
  47.  
  48.  
  49. DESCRIPTION
  50.      Tk_GetGC and Tk_FreeGC manage a collection of graphics  con-
  51.      texts  being  used  by an application.  The procedures allow
  52.      graphics contexts to be shared, thereby avoiding the  server
  53.      overhead  that  would  be  incurred  if  a  separate GC were
  54.      created for each use.  Tk_GetGC takes  arguments  describing
  55.      the desired graphics context and returns an X identifier for
  56.      a GC that fits the description.  The graphics  context  that
  57.      is  returned  will  have default values in all of the fields
  58.      not specified explicitly by _v_a_l_u_e_M_a_s_k and _v_a_l_u_e_P_t_r.
  59.  
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tk_GetGC(3)           Tk Library Procedures
  71.  
  72.  
  73.  
  74.      Tk_GetGC maintains a database of all the  graphics  contexts
  75.      it  has created.  Whenever possible, a call to Tk_GetGC will
  76.      return an existing graphics context rather than  creating  a
  77.      new  one.   This  approach  can  substantially reduce server
  78.      overhead, so Tk_GetGC should generally be used in preference
  79.      to  the Xlib procedure XCreateGC, which creates a new graph-
  80.      ics context on each call.
  81.  
  82.      Since the return values  of  Tk_GetGC  are  shared,  callers
  83.      should  never  modify  the  graphics  contexts  returned  by
  84.      Tk_GetGC.  If a graphics context must  be  modified  dynami-
  85.      cally,  then  it  should  be  created  by  calling XCreateGC
  86.      instead of Tk_GetGC.
  87.  
  88.      When a graphics  context  is  no  longer  needed,  Tk_FreeGC
  89.      should be called to release it.  There should be exactly one
  90.      call to Tk_FreeGC for each call to Tk_GetGC.  When a  graph-
  91.      ics  context  is no longer in use anywhere (i.e. it has been
  92.      freed as many times as it has been  gotten)  Tk_FreeGC  will
  93.      release it to the X server and delete it from the database.
  94.  
  95.  
  96. KEYWORDS
  97.      graphics context
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129. Tk                                                              2
  130.  
  131.  
  132.  
  133.